---
title: Maps
description: A library that provides access to Google Maps on Android and Apple Maps on iOS.
sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-maps'
packageName: 'expo-maps'
platforms: ['ios', 'android']
iconUrl: '/static/images/packages/expo-maps.png'
isAlpha: true
hasVideoLink: true
---

import APISection from '~/components/plugins/APISection';
import { APIInstallSection } from '~/components/plugins/InstallSection';
import { AndroidPermissions, IOSPermissions } from '~/components/plugins/permissions';
import { Collapsible } from '~/ui/components/Collapsible';
import { ConfigPluginExample, ConfigPluginProperties } from '~/ui/components/ConfigSection';
import { Step } from '~/ui/components/Step';
import { Tabs, Tab } from '~/ui/components/Tabs';
import { PlatformTag } from '~/ui/components/Tag/PlatformTag';
import { VideoBoxLink } from '~/ui/components/VideoBoxLink';

> **important** **This library is currently in alpha and will frequently experience breaking changes.** It is not available in the Expo Go app &ndash; use [development builds](/develop/development-builds/introduction/) to try it out.

## Installation

<APIInstallSection />

<br />
<VideoBoxLink videoId="jDCuaIQ9vd0" title="Watch: Expo Maps Deep Dive" />

## Configuration

Expo Maps provides access to the platform native map APIs on Android and iOS.

- **Apple Maps (available on <PlatformTag platform="ios" /> only)**. No additional configuration is required to use it after installing this package.
- **Google Maps (available on <PlatformTag platform="android" /> only)**. While Google provides a Google Maps SDK for iOS, Expo Maps supports it exclusively on Android. If you want to use Google Maps on iOS, you can look into using an [alternative library](https://reactnative.directory/) or [writing your own](/modules/overview/).

### Google Cloud API setup

**Before you can use Google Maps on Android**, you need to register a Google Cloud API project, enable the Maps SDK for Android, and add the associated configuration to your Expo project.

<Collapsible summary="Set up Google Maps on Android">

> If you have already registered a project for another Google service on Android, such as Google Sign In, you enable the **Maps SDK for Android** on your project and jump to step 4.

<Step label="1">
**Register a Google Cloud API project and enable the Maps SDK for Android**

- Open your browser to the [Google API Manager](https://console.developers.google.com/apis) and create a project.
- Once it's created, go to the project and enable the **Maps SDK for Android**.

</Step>

<Step label="2">
**Copy your app's SHA-1 certificate fingerprint**

<Tabs>
<Tab label="For Google Play Store">

- **If you are deploying your app to the Google Play Store**, you'll need to [upload your app binary to Google Play console](/submit/android/) at least once. This is required for Google to generate your app signing credentials.
- Go to the **[Google Play Console](https://play.google.com/console) > (your app) > Release > Setup > App integrity > App Signing**.
- Copy the value of **SHA-1 certificate fingerprint**.

</Tab>

<Tab label="For development builds">

- If you have already created a [development build](/develop/development-builds/introduction/), your project will be signed using a debug keystore.
- After the build is complete, go to your [project's dashboard](https://expo.dev/accounts/[username]/projects/[project-name]), then, under **Configure** > click **Credentials**.
- Under **Application Identifiers**, click your project's package name and under **Android Keystore** copy the value of **SHA-1 Certificate Fingerprint**.

</Tab>

</Tabs>

</Step>

<Step label="3">
**Create an API key**

- Go to [Google Cloud Credential manager](https://console.cloud.google.com/apis/credentials) and click **Create Credentials**, then **API Key**.
- In the modal, click **Edit API key**.
- Under **Key restrictions** > **Application restrictions**, choose **Android apps**.
- Under **Restrict usage to your Android apps**, click **Add an item**.
- Add your `android.package` from **app.json** (for example: `com.company.myapp`) to the package name field.
- Then, add the **SHA-1 certificate fingerprint's** value from step 2.
- Click **Done** and then click **Save**.

</Step>

<Step label="4">
**Add the API key to your project**

- Copy your **API Key** into your **app.json** under the `android.config.googleMaps.apiKey` field.
- Create a new development build, and you can now use the Google Maps API on Android with `expo-maps`.

</Step>

</Collapsible>

## Permissions

To display the user's location on the map, you need to declare and request location permission beforehand. You can configure this using its built-in [config plugin](/config-plugins/introduction/) if you use config plugins in your project ([Continuous Native Generation (CNG)](/workflow/continuous-native-generation/)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does **not** use CNG, then you'll need to manually configure the library.

<ConfigPluginExample>

```json app.json
{
  "expo": {
    "plugins": [
      [
        "expo-maps",
        {
          "requestLocationPermission": true,
          "locationPermission": "Allow $(PRODUCT_NAME) to use your location"
        }
      ]
    ]
  }
}
```

</ConfigPluginExample>

<ConfigPluginProperties
  properties={[
    {
      name: 'requestLocationPermission',
      description: 'A boolean to add permissions to **AndroidManifest.xml** and **Info.plist**.',
      default: 'false',
    },
    {
      name: 'locationPermission',
      platform: 'ios',
      description:
        'A string to set the [`NSLocationWhenInUseUsageDescription`](#permission-nslocationwheninuseusagedescription) permission message.',
      default: '"Allow $(PRODUCT_NAME) to use your location"',
    },
  ]}
/>

## Usage

```tsx
import { AppleMaps, GoogleMaps } from 'expo-maps';
import { Platform, Text } from 'react-native';

export default function App() {
  if (Platform.OS === 'ios') {
    return <AppleMaps.View style={{ flex: 1 }} />;
  } else if (Platform.OS === 'android') {
    return <GoogleMaps.View style={{ flex: 1 }} />;
  } else {
    return <Text>Maps are only available on Android and iOS</Text>;
  }
}
```

## API

```js
import { AppleMaps, GoogleMaps } from 'expo-maps';

// ApplesMaps.View and GoogleMaps.View are the React components
```

<APISection packageName="expo-maps" apiName="Maps" />

## Permissions

### Android

To show the user's location on the map, the `expo-maps` library requires the following permissions:

- `ACCESS_COARSE_LOCATION`: for approximate device location
- `ACCESS_FINE_LOCATION`: for precise device location

<AndroidPermissions
  permissions={[
    'ACCESS_COARSE_LOCATION',
    'ACCESS_FINE_LOCATION',
    'FOREGROUND_SERVICE',
    'FOREGROUND_SERVICE_LOCATION',
    'ACCESS_BACKGROUND_LOCATION',
  ]}
/>

### iOS

The following usage description keys are used by this library:

<IOSPermissions permissions={['NSLocationWhenInUseUsageDescription']} />
